Inside Macintosh: QuickDraw GX Printing Extensions and Drivers /

Chapter 6 - Printing Resources / Printing Resources Reference

Resources Used Only in Printer Drivers

The Communications ('comm') Resource

Each communications ('comm') resource, of type gxDeviceCommunicationsType, defines parameters for a specific communications protocol that is supported by a printer driver. You must include one communications resource for each entry in your look resource. You can define printer communications resources in four different formats: serial communications resources, PAP communications resources, PrinterShare communications resources, and SCSI communications resources.

Serial Communications Resource

You need to define a serial communications resource to support serial communications in your driver. Figure 6-11 shows the structure of this form of a communications resource.

Figure 6-11 The serial communications resource

The serial communications resource consists of a communications type identifier and a number of input and output communications values.

• Type identifier. 'SPTL' (or the constant Serial). Used to identify serial communications resources.
• Output baud-rate value. The baud rate used for output, constants for which are shown in Table 6-14.
• Output parity value. The parity type used for output, constants for which are shown in Table 6-15.
• Output stop-bits value. The number of stop bits used for output, constants for which are shown in Table 6-16.
• Output data-bits value. The number of data bits used for output, constants for which are shown in Table 6-17.
• Output handshaking. The handshaking protocol used for output, as defined on page 6-40.
• Input baud-rate value. The input baud rate, constants for which are shown in
  Table 6-14.
• Input parity value. The parity type used for input, constants for which are shown in Table 6-15.
• Input stop-bits value. The number of stop bits used for input, constants for which are shown in Table 6-16.
• Input data-bits value. The number of data bits used for input, constants for which are shown in Table 6-17.
• Input handshaking. The handshaking protocol used for input, as defined on page 6-40.
• Input buffer size. The number of bytes in the serial input buffer.
• Input port name. The name of the input port, filled in by the Chooser.
• Output port name. The name of the output port, filled in by the Chooser.

Table 6-14 shows the values that you can use to specify the baud rate in serial communications resources.

Table 6-14 Constants for the baud rate

Constant	Explanation
baud300	300 baud
baud600	600 baud
baud1200	1200 baud
baud1800	1800 baud
baud2400	2400 baud
baud3600	3600 baud
baud4800	4800 baud
baud7200	7200 baud
baud9600	9600 baud
baud19200	19200 baud
baud38400	38400 baud
baud57600	57600 baud

Table 6-15 shows the constants that you can use to specify parity values in serial communications resources.

Table 6-15 Parity constants

Constant	Explanation
noParity	Parity not used
oddParity	Use odd parity
evenParity	Use even parity

Table 6-16 shows the constants that you can use to specify stop-bits values in serial communications resources.

Table 6-16 Constants for stop bits

Constant	Explanation
oneStop	1
oneFiveStop	1.5
twoStop	2

Table 6-17 shows the constants that you can use to specify data-bits values in serial communications resources.

Table 6-17 Constants for data bits

Constant	Explanation
data5	5 data bits
data6	6 data bits
data7	7 data bits
data8	8 data bits

The values that are used to define input and output handshaking in the serial communications resource are shown in Figure 6-12.

Figure 6-12 Input and output handshaking values

The handshake values define parameters of how the driver and the device communicate.

• XOn/XOff output flow-control flag. A value that defines whether output flow control is enabled or disabled. If this value is nonzero, XOn/XOff output flow is enabled.
• CTS hardware handshake flag. A value that defines whether CTS hardware handshake is enabled or disabled. If this value is nonzero, CTS hardware handshake is enabled.
• XOn character. The XOn character used for XOn/XOff flow control.
• XOff character. The XOff character used for XOn/XOff flow control.
• Handshake errors. The types of errors that cause input requests to be aborted. The constants that you can use for the error types are shown in Table 6-18. These constants can be combined into a single value to specify all of the error types that cause input requests to be aborted.
• Status changes. A value that indicates whether changes in the CTS or break status cause the Serial Driver to post device-driver events. The constants that you can use for the status event types are shown in Table 6-18. These constants can be combined into a single value to specify all of the status changes that cause device driver events to be posted.

  Use of the status change option is discouraged because interrupts will be disabled for a long time while the driver event is posted.

• XOn/XOff input flow-control flag. A value that defines whether input flow control is enabled or disabled. If this value is nonzero, XOn/XOff input flow is enabled.
• Unused. A single byte reserved for use in the future.

Table 6-18 shows the constants that you can use to specify handshake error-handling in serial communications resources.

Table 6-18 Handshake error types

Constant	Value	Explanation
parityErr	16	Abort the input request if a parity error occurs
hwOverrunErr	32	Abort the input request if a hardware overrun error occurs
framingErr	64	Abort the input request if a framing error occurs

Table 6-19 shows the constants that you can use to specify which status changes cause driver events to be posted.

Table 6-19 Status changes that cause driver events to be posted

Constant	Value	Explanation
ctsEvent	32	Causes driver events to be posted if the CTS status changes
breakEvent	128	Causes driver events to be posted if the break status changes

Listing 6-10 shows an example of a serial communications resource.

Listing 6-10 An example of a serial communications resource

resource gxDeviceCommunicationsType (-4095, sysHeap, purgeable)
{
   Serial
      {
      baud9600,      /* output baud rate */
      noParity,      /* output parity */
      oneStop,       /* output stop bits */
      data8,         /* output data size */
      0x00010000,    /* output handshaking */
      0x00000000, 
      baud9600,      /* input baud rate */
      noParity,      /* input parity */
      oneStop,       /* input stop bits */
      data8,         /* input data size */
      0,             /* input handshaking */
      0,
      1024,          /* input buffer size */
      ".Ain",        /* input driver name; Chooser fills in */
      ".Aout"        /* output driver name; Chooser fills in  */
      };
};

This example defines a serial port that supports input and output using the same parameters: 9600 baud, no parity, 1 stop bit, and 8 data bits. The input buffer size is
1024 bytes long.

AppleTalk PAP Communications Resource

You need to define a PAP communications resource to support the AppleTalk Printer Access Protocol in your driver. Figure 6-13 shows the structure of this form of a communications resource.

Figure 6-13 The PAP communications resource

The PAP communications resource consists of a communications type identifier and a number of input and output communications values.

• Type identifier. 'PPTL'(or the constant PAP). Used to identify PAP communications resources.
• Flow quantum. A value that specifies the flow quantum, which is the number of packets that your device sends or receives in one transaction. The flow quantum value is hardware dependent: it is defined by the hardware manufacturer. The flow quantum value for LaserWriter printers is 8, the value for ImageWriters is 1. You can read more about this value in Inside AppleTalk.
• AppleTalk printer name. A string value that is filled in by the Chooser with the compacted, network name of the printer.
• Filler. An unused byte added for alignment purposes.
• Open status buffer pointer. An internally used value. This must be 0 in your resource definition.
• Read-byte pointer. An internally used value. This must be 0 in your resource definition.
• Write-byte pointer. An internally used value. This must be 0 in your resource definition.
• Network address. An internally used value. This must be 0 in your resource definition.

Listing 6-11 shows an example of a PAP communications resource that defines an AppleTalk connection for an ImageWriter II printer, which uses a flow quantum value of 1.

Listing 6-11 An example of an AppleTalk communications resource

resource gxDeviceCommunicationsType(-4096, sysHeap, purgeable)
{
   PAP
      {
      1,             /* flow quantum */
      ""             /* AppleTalk address; Chooser fills in */
      0, 0, 0, 0
      };
};

PrinterShare Communications Resource

You need to define a PrinterShare communications reource to support a server connection to your driver. Figure 6-14 shows the structure of this form of a communications resource.

Figure 6-14 The PrinterShare communications resource

The PrinterShare communications resource consists of a communications type identifier and a number of input and output communications values.

• Type identifier. 'ptsr'(or the constant PrinterShare). Used to identify PrinterShare communications resources.
• AppleTalk printer name. A string value filled in by the Chooser with the compacted, network name of the printer.
• Filler. An unused byte added for alignment purposes.
• Network address. The most recent network address of the printer. This value is filled in at run time and needs to be 0 in your resource definition.

Listing 6-12 shows an example of a PrinterShare communications resource that defines a print server's connection for an ImageWriter II printer.

Listing 6-12 An example of a PrinterShare communications resource

resource gxDeviceCommunicationsType (-4094, sysHeap, purgeable)
{
   PrinterShare,
      {
      "",            /* AppleTalk address; Chooser fills in */
      0
      };
};

SCSI Communications Resource

You need to define a SCSI communications resource for SCSI output devices. The structure of this form of a communications resource is shown in Figure 6-15. Although QuickDraw GX provides the SCSI communications resource, it does not provide a default implementation of the device communications messages for SCSI devices. If you are implementing a printer driver for a SCSI device, you must override the device communications messages, which are described in the chapter "Printing Messages" in this book.

Figure 6-15 The SCSI communications resource

The SCSI communications resource consists of a communications type identifier and a number of SCSI control values.

• Type identifier. 'sPTL'(or the constant SCSI) is used to identify SCSI communications resources.
• Release routine. An internally used value. This must be 0 in your resource definition.
• Data transfer attributes. The SCSI input/output attributes that apply to data transfers.
• Status byte location. An internally used value. This must be 0 in your resource definition.
• Bus location. The SCSI bus number for the device. The value 0 indicates the motherboard.
• Device number. The SCSI device number for the device.
• Transfer size. The number of bytes for each transfer (at the SCSI TIB level). If this value is 0, it is ignored.
• Acquire routine. An internally used value. This must be 0 in your resource definition.
• Device type. The type of SCSI device to look for.
• Minimum response size. The minimum amount of data, in bytes, in the response data.
• Response offset. The location in the response data to look for the response string. This is specified as a byte offset from the start of the response data.
• Response string. The string to look for in the response data.

Listing 6-13 shows an example of a SCSI communications resource that defines a SCSI communications connection for a LaserWriter IISC printer.

Listing 6-13 An example of a SCSI communications resource

resource gxDeviceCommunicationsType (-4095, sysHeap, purgeable)
{
   SCSI
   {
      0,          /* release device routine */
      0,          /* I/O attibutes */
      0,          /* status byte */
      0,          /* SCSI bus number */
      0,          /* SCSI ID */
      0,          /* chunk level */
      0,          /* acquire routine (use default) */
      2,          /* device type to look for */
      27,         /* minimum length of additional response data */
      8,          /* bytes from start for search */
      "APPLE   PERSONAL LASER  ",   /* search string */
   };
};

Note

QuickDraw GX provides the SCSI communications resource type and supports it in the Chooser. However, QuickDraw GX does not provide a default implementation of SCSI printer communications. If you are implementing a driver for a SCSI printer, you must override all of the communications messages. These messages are described in the chapter "Printing Messages" in this book.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help